【Grunt】styledoccoでCSSスタイルガイドを自動作成をしてみる。

アジェンダ

• styledoccoとは?
• 導入準備
• Gruntの設定
• CSSのコメント記述方法
• 動作確認

styledoccoとは？

Node.jsを使用して、CSSのスタイルガイドを作成してくれます。

導入準備

今回はNode.jsのパッケージを使用します。当ブログでも環境構築のご紹介していますので、以下を参考にNode.jsをインストールしてください。

• 【もうすぐバレンタインデー】デザイナーがCoffeeScprit、TypeScriptの開発環境（Win/Mac）をインストールしてみる

今回の動作環境

• OS:windows7

Gruntをインストールする。

今回styledoccoを自動化するに際に、Gruntにお世話になるので以下コマンドからGruntをインスールします。

npm install -g grunt
npm install -g grunt-cli

gruntで自動化してみる。

作業フォルダの構成

今回はdocsフォルダ内のstyledoccoフォルダにスタイルガイドを作成したいと思います。

package.jsonの作成

作業ファイルだ内に、package.jsonを作成します。package.jsonには今回使用するプラグイン等を記述しておきます。

今回使用したプラグイン

• grunt-styleguide : cssコードをドキュメント出力してくれます。(今回のメイン)
• grunt-contrib-clean : 指定したフォルダ、ファイルの削除をしれくれます。
• grunt-contrib-watch : ファイルの更新等を自動感知して処理を実行してくれます。

package.json

{
  "author": "Takashi Kiyota",
  "name": "StyleDocco",
  "version": "0.9.1",
  "devDependencies": {
    "grunt": "",
    "grunt-contrib-watch" : "",
    "grunt-contrib-clean" : "",
    "grunt-styleguide"    : ""
  }
}

Nodeパッケージをインストールします。

プラグインのインストールしてみます、黒い画面(コマンドプロンプト等)から作業ファイルまで移動し以下のコマンドを入力します。

cd C:\\作業ディレクトリに移動
npm install

正常にインストールできると、「node_modules」ファイルが作成され中にプラグインがインストールされています。

Gruntfile.jsの作成

Gruntの設定ファイルを作成します。

Gruntfile.js

module.exports = function (grunt) {

    'use strict';

    [
        'grunt-styleguide',
        'grunt-contrib-clean',
        'grunt-contrib-watch'
    ].forEach(function (name) {
            if (!/template/.test(name)) {
                grunt.loadNpmTasks(name);
            }
        });

    grunt.initConfig({

        watch: {
            styleguide: {
                //css配下のcssファイルを監視
                files: ['css/**/*.css'],
                //cleanタスク、styleguideタスクを実行
                tasks: ['clean' , 'styleguide']
            }
        },

        clean: ['docs/styledocco'],

        styleguide: {
            dist: {
                name: 'Style Guide',
                options: {
                    framework: {
                        name: 'styledocco'
                    }
                },
                files: {
                    'docs/styledocco': 'css/**/*.css'
                }
            }
        }

    });

    grunt.registerTask('default', ['watch']);
    grunt.registerTask('build', ['styleguide']);
};

なぜかstyledoccoの2回目以降の上書きが動作してくれなかったので、clean: ['docs/styledocco']で一旦フォルダ内をクリアして、再度出力するようにしています。

CSSのコメント記述方法

styledoccoでは、CSSファイル内でのコメント記述する際は、MarkDown方式で記述するのがルールとなっています。

sample.cssの記述例

/*
# タイトル

説明文言

```
<div class="btn-group">
  <button type="button" class="btn btn-default">Left</button>
</div>
```
*/

.btn {
  display: inline-block;
  padding: 6px 12px;
  margin-bottom: 0;
  font-size: 14px;
  font-weight: bold;
  line-height: 1.428571429;
  text-align: center;
  white-space: nowrap;
  vertical-align: middle;
  cursor: pointer;
  border: 1px solid transparent;
  border-radius: 4px;
  -webkit-user-select: none;
     -moz-user-select: none;
      -ms-user-select: none;
       -o-user-select: none;
          user-select: none;
}

動作確認

それでは動作を確認したいと思います。黒い画面(コマンドプロンプト)からgurnt起動をさせます。

cd C:\\作業ディレクトリに移動
grunt

起動すると、指定フォルダ内を監視してくれます。

次にsample.cssが更新されるとgurnt側がcssの更新を検知しstyleguideタスクを走らせてくれます。
「docs/styledocco」フォルダ内にドキュメントが出力されました。

出力されたドキュメントを確認する

「docs/styledocco」フォルダ内に出力されたファイルを確認してみます。

cssコード内に記入した、markdown形式のコメント等が出力されています。

まとめ

Gruntを使用して、styledoccoの自動化をためしてみました。複数人のチームでデザイン・マークアップ作業する際、チーム内のスタイルガイドラインの共有が簡単に行えて便利ですね！

参考にさせていただたい記事

• StyleDoccoでstyleguideを作成